home *** CD-ROM | disk | FTP | other *** search
/ 17 Bit Software 3: The Continuation / 17-Bit_The_Continuation_Disc.iso / amigan / amigan 18 / rexxserial / rexxserdev.doc < prev    next >
Encoding:
Text File  |  1994-01-27  |  8.5 KB  |  235 lines
  1.                   Documentation for rexxserdev.library
  2.  
  3. copyright © 1988       by Joseph M. Stivaletta        All rights reserved.
  4. --------------------------------------------------------------------------
  5.  
  6. This is the beta version of my serial device function library for ARexx.
  7. Most of the functions have been implemented.  I have not yet incorporated
  8. xon/xoff flow control.  I hope to have these in the next version.
  9.  
  10. This library uses ARP functions.  Therefore, you must have arp.library in
  11. your LIBS: directory.  You must also place my library into your LIBS:
  12. directory also.  To use the Arexx serial device library, you must add it
  13. to the global library list using the either the addlib() function or the
  14. rxlib() command
  15.  
  16. The current version number of this library is 1 and the query function offset
  17. is -30.  examples follow:
  18.  
  19.    addlib( 'rexxserdev.library', 0, -30, 1 )
  20.    rxlib rexxserdev.library 0 -30 1
  21.  
  22.  
  23. The rexxserdev.library was written to provide an easy to use interface
  24. between ARexx programs and the Amiga's internal serial device.  The serial
  25. device is opened as shared so take care when accessing the serial device
  26. from more than one application.  All I/O requests to the serial device are
  27. synchronous not asynchronous.  Therefore, a call to a function will not
  28. return to the application until that function is completed.  Due to the
  29. synchronous nature of the library functions the SerStart() and SerStop()
  30. functions may not work as designed for write calls.  The actual effect
  31. of these calls has yet to be determined.  At the current time I have not
  32. implemented SerStart(), SerStop() and SerGetParms().
  33.  
  34.  
  35. ==========================================================================
  36.                            Using the functions
  37.  
  38.  
  39. SerOpen()
  40. Usage: boolean = SerOpen()
  41. Opens the serial device and allocates the I/O requests and reply ports.
  42. Example:
  43.          say SerOpen()          ==> 1
  44.  
  45.  
  46. SerClose()
  47. Usage: boolean = SerClose()
  48. Closes the serial device and deallocates the I/O requests and reply ports.
  49. Example:
  50.          say SerClose()          ==> 1
  51.  
  52.  
  53. SerClear()
  54. Usage: boolean = SerClear()
  55. Clears the internal read buffer.
  56. Example:
  57.          say SerClear()         ==> 1
  58.  
  59.  
  60. SerFlush()
  61. Usage: boolean = SerFlush({'R' | 'W'})
  62. Aborts all queued I/O requests in either the read or write request queue.
  63. Example:
  64.          say SerFlush( 'R' )    ==> 1
  65.  
  66.  
  67. SerRead()
  68. Usage: charsRcvd = SerRead(buffer,length)
  69. Read a number of characters from the serial port.  The number of characters
  70. read is specified by length.  The buffer is an internal read buffer supplied
  71. by the calling ARexx program.  This buffer is for use by the
  72. rexxserdev.library and not by the ARexx application.
  73. Example:
  74.          block = allocmem( 20 ) 
  75.          addr = c2d( block )
  76.          say SerRead( addr, 20 )    ==> A string of 20 chara
  77.  
  78.  
  79. SerReset()
  80. Usage: boolean = SerReset()
  81. Reinitializes the serial device to it's default state.
  82. Example:
  83.          say SerReset()         ==> 1
  84.  
  85.  
  86. SerStart()
  87. Usage: boolean = SerStart({'R' | 'W'})
  88. Restarts reading or writing stopped by a previous SerStop() function.  Not
  89. yet implemented.
  90. Examples:
  91.          say SerStart( 'W' )       ==> 1
  92.  
  93.  
  94. SerStop()
  95. Usage: boolean = SerStop({'R' | 'W'})
  96. Stops the currently executing read or write command.  Not yet implemented.
  97. Example:
  98.          say SerStop( 'R' )        ==> 1
  99.  
  100.  
  101. SerWrite()
  102. Usage: boolean = SerWrite(buffer,length)
  103. Sends the characters in the buffer to the serial port.
  104. Example:
  105.          text = 'send stuff out port'
  106.          say SerWrite( text, length( text ) )       ==> 1
  107.  
  108.  
  109. SerBreak()
  110. Usage: boolean = SerBreak()
  111. Sends a break signal.
  112. Examples:
  113.          say SerBreak()       ==> 1
  114.  
  115.  
  116. SerQuery()
  117. Usage: status = SerQuery()
  118. Returns status of the serial device.  The first substring indicates the
  119. validity of the rest of the string.  0 indicates that an error was returned
  120. from the query command and no additional information is contained within
  121. the status string.  1 indicates that the call was successful and the string
  122. contains two more substrings.  The second substring is the number in decimal
  123. ASCII of the number of characters currently in the internal read buffer.
  124. The third substring is the status word in decimal ASCII it is defined as 
  125. follows:
  126.             Bit no.     Meaning of Bit
  127.  
  128.             0-2         Reserved
  129.             3           DSR - Data Set Ready (bit = 0)
  130.             4           CTS - Clear To Send (bit = 0)
  131.             5           DCD - Data Carrier Detect (bit = 0)
  132.             6           RTS - Ready To Send (bit = 0)
  133.             7           DTR - Data Terminal Ready (bit = 0)
  134.             8           Read buffer overflow (bit = 1)
  135.             9           Break signal sent (bit = 1)
  136.             10          Break signal received (bit = 1)
  137.             11          Transmit XOFF (bit = 1)
  138.             12          Received XOFF (bit = 1)
  139.             13-15       Reserved
  140. Examples:
  141.          say SerQuery()       ==> 1 23 0 
  142.                                   | |  +--> Status bits
  143.                                   | +-----> Number of characters received
  144.                                   +-------> Validity of status information
  145.  
  146.  
  147. SerSetParms()
  148. Usage: boolean = SerSetParms(baud,databits,paritybits,stopbits,[flowCtl],[brkTime])
  149. Sets the serial device parameters defined below.  The optional flowCtl and
  150. brkTime parameters are not yet implemented.  I have not yet incorporated
  151. SERF_RAD_BOOGIE so take care when using very high baud rates.
  152.  
  153. baud = allowed range is from 110 to 29,200
  154. databits = allowed range from 1 to 8
  155. paritybits = {'N' | 'E' | 'O' | 'M' | 'S'}
  156.               'N' = No parity
  157.               'E' = Even parity
  158.               'O' = Odd parity
  159.               'M' = Mark parity
  160.               'S' = Space parity
  161. stopbits = {'1' | '2'}
  162. flowCtl = {'0' | '1'}
  163.            '0' = Disable Xon/Xoff flow control
  164.            '1' = Enable Xon/Xoff flow control
  165.           the default is disabled Xon/Xoff flow control
  166. brkTime = duration of break signal in microseconds; the default value is
  167.           250,000 microseconds.
  168.  
  169. Examples:
  170.          say SerSetParms( 9600, 7, e, 1 )      ==> 1
  171.  
  172.  
  173. SerGetParms()
  174. Usage: SerGetParms()
  175. This function returns the current serial device parameters.  This function
  176. has not been implemented yet.
  177. Examples:
  178.          say SerGetParms()         ==> 1 9600 7 e 1 2500000 0
  179.  
  180.  
  181. ==========================================================================
  182.                               User rights
  183.  
  184. This is a beta version of my library and I do not guarantee that it is
  185. free from bugs.  It has been tested but not rigorously.  I am making it
  186. available now so that people can begin using it.  I will try to keep
  187. future versions downwardly compatible but make no promises that it will
  188. not change slightly based on user feedback.
  189.  
  190. These programs are freely distributable in the public domain as long as
  191. this document is included.  I retain the rights to their use.  This means
  192. that they cannot be sold for profit by anyone without my written permission.
  193.  
  194.  
  195. ==========================================================================
  196.                             Disclaimer BS
  197.  
  198. If this software, blows up your machine, melts you hard drive, causes
  199. loss of hair, mental anguish, mental disorders, or marital difficuties
  200. ending in divorce, I will not be held liable.  I make no warranties, either
  201. expressed or implied, with respect to the programs described herein, 
  202. their quality, performance, or fitness for any particular purpose.  These
  203. programs are distributed "AS IS." The entire risk as to their quality and
  204. performance is with the user.  I promise only to fix the bugs and to
  205. improve and enhance the code as I deem able in my spare time.
  206.  
  207.  
  208. ==========================================================================
  209.                             Problem reporting
  210.  
  211. If you find any errors or have any problems, your flames can reach me
  212. at the following locations:
  213.  
  214. Amiga Colony BBS (617-641-1629): 
  215. Name: Joe Stivaletta
  216.  
  217. IDCMP BBS (617-769-3172):
  218. Name: Joe Stivaletta
  219.  
  220. CompuServe:
  221. PIN: 72155,516
  222.  
  223. People Link:
  224. ID: Blackhawk
  225.  
  226. Delphi:
  227. ID: Blackhawk
  228.  
  229. Bix:
  230. ID: jstivaletta
  231.                                           Joseph M. Stivaletta
  232.                                           P.O. Box 125
  233.                                           Bedford, MA      01730
  234.                                           14 June 1988